The PC-SIG Library 10

home *** CD-ROM | disk | FTP | other *** search

/ The PC-SIG Library 10 / The PC-Sig Library - Shareware for the IBM PC and Compatibles (PC-SIG)(Tenth Edition Disks 1-2804)(1991).iso / PC_SIGCD / 06 / 8 / DISK0685.ZIP / FORTH.ARC / 4TH-UG.DOC < prev next >

Wrap

Text File | 1987-05-17 | 95KB | 2,150 lines

User's Guide for 8086/8088 FIG-FORTH Release 1.0 With Compiler Security and Variable Length Words March 1981 ================================ MS-DOS File Interface and Revisions July 1983 This program and documentation are released to the public domain. The FIG-FORTH listing is made available by the FORTH Interest Group, P.O. Box 8231, San Jose, CA 95155. Modified for MS-DOS and documented by J.E. Smith, U. of Penn./Dept.of Chem, Philadelphia, PA 19104 (to whom inquiries should be directed). Any further distribution of this software is strictly encouraged, as long as you don't get rich and keep it all for yourself. If you modify this revised version and re-distribute your own version, it would be polite to notify the author of these revisions, and to take responsibility for your modifications. 8086/8088 FIG-FORTH User's Guide Page 2 2.0 Quick Reference This is a summary of information necessary to use FIG-FORTH and its documentation. 2.1 System Requirements FORTH requires the following system resources: * an 8086 or 8088 CPU running MS-DOS version 1.10 or 1.25 * 64K of available RAM, or about 100K total * one or two disk drives 2.2 Invocation FORTH is started by typing the following in response to the COMMAND prompt. FORTH <commands> Where <commands> is an optional list of FORTH words to be executed. FORTH normally uses a special disk. To use MS-DOS files, the following commands are available: A: selects drive A B: selects drive B DIR" <filename>" lists matching file information FILES" <filename>" lists matching file names USING" <filename>" selects <filename> for screen access EOF closes current screen file LOAD" <filename>" loads the screens in <filename> ERASE" <filename>" erases any matching files Note: NEVER change any disk while FORTH is using a file on that disk! Study the section below regarding disk operations. 8086/8088 FIG-FORTH User's Guide Page 3 2.3 Provided Documentation This document contains three main sections: * FORTH user's guide The user's guide tells you how to use the special features in this version of FORTH. * FORTH technical reference The technical reference contains information regarding modifications and additions to the FORTH interpreter/compiler relative to the FIG implementation. * FORTH glossary This is a list and explanation of each FORTH word which has been changed or added to this version of FORTH. 8086/8088 FIG-FORTH User's Guide Page 4 3.0 Introduction This document describes changes and additions to FIG-FORTH v1.0 which is distributed by the FORTH Interest Group P.O. Box 8231 San Jose, CA 95155 as modified to run under MS-DOS by Joe Smith University of Pennsylvania Dept. of Chemistry 250 S. 33rd St. Philadelphia, PA 19104 This software and the accompanying documentation is available from SIG/86 c/o Joseph Boykin 47-4 Sheridan Dr. Shrewsbury, MA 01545 This version of FIG-FORTH incorporates a number of significant changes to the FIG version. The following is a partial list: * written for Microsoft's MACRO-86 assembler * full MS-DOS file interaction, as well as usual FORTH disk access * all i/o is vectored and may be re-directed within FORTH * command line interpretation Modifications to the FIG-FORTH implementation were undertaken to alleviate several problems. First, the FIG version is for CP/M-86. Once FORTH was running under MS-DOS, the lack of a file interface soon became intolerable. Also, the assembly source for Seattle Computer's assembler was not transportable to other MS-DOS systems. The translation to Microsoft's MACRO-86 was begun in January of 1983 and the file system interface was completed the following June. My original goal was to install a language for my own use. That is still my primary concern. Accordingly, this version of the language is recommended for people who are familiar 8086/8088 FIG-FORTH User's Guide Page 5 with their computer, and (somewhat less importantly) familiar with FORTH. If you are new to FORTH, you will have to dig for some of the basic information. (some helpful references are listed at the end of this guide). If you are a person who enjoys understanding and tinkering with the mechanisms (read 'hacker') you should feel right at home. If you are an experienced FORTH wizard, you can tell me all the things I did wrong! The author (J.E.S.) gratefully acknowledges the efforts of the FORTH Interest Group (FIG) in providing FORTH source code. FORTH owes much of its popularity to the work of this organization, it was the first significant software to run on my system (even before I had disks) and without them this implementation would certainly not exist. Also, special thanks to Joseph Boykin, whose TOP text processor formatted this document. 8086/8088 FIG-FORTH User's Guide Page 6 4.0 User's Guide This documentation presents specific details necessary to use this version of FORTH under MS-DOS. It is not a user's guide to FORTH in general. Several introductory references are given at the end of this guide 4.1 System Requirements The FORTH interpreter/compiler as distributed requires: * an 8086/8088 computer running MS-DOS version 1.10 or 1.25 * 64K of RAM, or 96K total, including the operating system * one or more disk drives These requirements may be changed to almost any configuration by changing options in the assembly source and re-assembling. This process requires: * All of the above requirements, plus another 64K of RAM, or 128K total (for MACRO-86) * the MACRO-86 macro assembler, or its equivalent * the LINK-86 linker, or its equivalent * the EXE2BIN program to convert the linker output to a .COM file See the section below, "Modifying FORTH", and the technical reference for further information. 8086/8088 FIG-FORTH User's Guide Page 7 4.2 FORTH, Calculator Style The simplest mode of interaction with FORTH is through the system console. You type commands, FORTH interprets them and carries out your orders; much the same as using a powerful, programmable calculator. 4.2.1 Getting Started FORTH is invoked from MS-DOS by typing: FORTH <optional command list> in response to COMMAND's prompt. This will load and execute the FORTH interpreter. FORTH will initialize itself and print a banner something like 8086 FIG-FORTH Version 1.1A Then, FORTH begins executing any commands you give it. If there was anything else on the command line, i.e. <command list> was present, FORTH attempts to interpret it. Thus, if you wanted to find out what 8086 is in hex, you could type: A:FORTH 8086 HEX . BYE and FORTH would reply: 8086 FIG-FORTH Version 1.1A 1F96 A: If nothing was passed on the command line, FORTH simply types a carriage return and waits for you. The command list is limited to a total of 80 characters. If you type a carriage return at this point, FORTH should respond: "ok". If it doesn't, you have a problem. 4.2.2 Communicating With FORTH Keyboard entries are handled by the FORTH word EXPECT. EXPECT only recognizes two special keys: <DELETE> and <CR>. Any other key is presumed to be a valid character. No MS-DOS editing functions are available. The exact key which FORTH recognizes as <DELETE> defaults to ASCII DEL. This may be easily changed to any other key. The section below on modifying FORTH tells how to change the backspace character. If you type <DELETE>, EXPECT will delete the last character entered. If you try to go past the beginning 8086/8088 FIG-FORTH User's Guide Page 8 of the line, the terminal should beep and leave the cursor in the first column. 4.2.3 Special Functions While no editing functions are provided, MS-DOS does respond to some other special keys. Any console output may be paused by typing ^S. Printer output is toggled using ^P/^N. Because MS-DOS intercepts these keys, FORTH will never see them. Another function, the interrupt key ^C, has variable effects. Normally, pressing ^C causes the currently executing FORTH word to be interrupted. Control is passed to the FORTH word (ABORT) which usually aborts the current word and resets the interpreter. This process may be changed to provide more intelligent interrupt handling. Refer to the last part of the technical reference section on "Modifying FORTH" for more information. There are a number of assembly options which may affect the exact way these keys are handled. See the technical reference section entitled "installation dependent code" for further information. 4.2.4 New Definitions One command FORTH accepts is the colon ":". Colon is a command to begin compiling the following text as a new definition. No "ok" will appear until you have successfully completed your definition and ended it with a semicolon ";". The definition may be spread out over as many lines as you need, up to 80 characters on each line. Until you end a line by typing <CR>, you may back up and change it. Once you go on to the next line, no editing is possible. FORTH will make you aware of any errors in the definition. If you make a mistake, the whole definition must be entered again. Try the following definition: : STAR 42 EMIT ; FORTH should respond "ok" after you hit return. Now test STAR by typing: STAR<CR>. FORTH should print "*ok". If that worked, try this one: : MILKY-WAY BEGIN STAR SPACE SPACE ?TERMINAL UNTIL ; Remember, no "ok" will be printed until you finish the definition with the semicolon. Any leading spaces are ignored. Test MILKY-WAY as with STAR. When you get tired 8086/8088 FIG-FORTH User's Guide Page 9 of star-gazing, stop the program by hitting any key. The stars should stop, and FORTH should inform you that everything is "ok". You can also pause the execution of MILKY-WAY using ^S, or abort it using ^C. You can experiment with other definitions, but having no way of modifying the functions without re-typing them soon becomes a serious problem. The next section tells how to edit and load definitions stored on your disk. Don't try any disk operations until you have read the next section. 4.2.5 Exiting FORTH To return to MS-DOS, say "BYE" to FORTH. 8086/8088 FIG-FORTH User's Guide Page 10 4.3 Using the Disk Standard FORTH supports only the most primitive of file structures. FORTH views the disk as a linear array of blocks which may be accessed in any order. A disk block formatted as 16 lines of 64 characters is called a screen. In the standard configuration, FIG-FORTH bypasses the operating system file structure. This means that FORTH must have a disk all to itself. While there are advantages to this arrangement (no directory overhead, simple disk interface, portability across operating systems, for instance), it is often inconvenient that FORTH should totally ignore its host operating system's files. To deal with this conflict, and yet maintain compatibility with standard FORTH disk access, the FIG-FORTH model was changed. The words which do all disk access, BLOCK-READ and BLOCK-WRITE, can now be assigned to any function. Thus, by telling BLOCK-READ/WRITE to use a file instead of the disk directly, all of the standard FORTH disk words will refer to blocks of that file. The user can easily switch between the two modes, or use one exclusively. Also, all of the usual disk words will work on a file as well as the old FORTH disk. 4.3.1 Creating and Editing Definitions There are three editors distributed with the package. Unfortunately, there isn't time or space to describe their use here. All are described elsewhere, however. The editors provided include: * two line-oriented editors: the FORTH Inc. editor described in Leo Brodie's "STARTING FORTH" and the FIG portable editor described in the FIG installation manual. * a screen editor described in Dr. Dobb's Journal No. 59. This editor is configured for the Televideo 950 terminal, and must be modified for any other terminal. Any of these may be used with either screen files or FORTH disks. All examples in this guide will refer to the editor described by Brodie, which has been compiled and included in the FORTH.COM file. 8086/8088 FIG-FORTH User's Guide Page 11 4.3.2 FORTH Disk Access After a COLD start, any disk words will access a FORTH disk. If you start FORTH and type "4 LIST", it assumes you are asking to see the fourth disk block. In this mode, all disk transfers bypass the file system. The user has access to all blocks on the disk, and if more than one disk is available, FORTH will treat them as one disk of twice the capacity. Once you use a screen file, you must execute SWITCH to get back to the FORTH disk. This should remind you to "switch" your FIG-FORTH disk for the MS-DOS disk. The disk interface allows you to use only one format at a time. That is, FORTH cannot automatically adapt to different FORTH disk formats the way MS-DOS can. By changing the constants that describe the disk, you can manually change formats to any supported by your i/o system. To find what format FORTH expects, type B/BUF REC/BLK / . This gives the sector size in bytes. To determine the capacity of the disk FORTH expects, display the constants BLK/DRIVE, MAXDRIVE, and MAXBLOCK. The 8-inch format is 128 bytes/sector, 52 sectors/track, 77 tracks per disk. The 5-inch disks are 512 bytes/sector, 8 sectors/track, 40 tracks per disk. 4.3.3 Screen File Access This version of FORTH includes an interface to the MS-DOS file system. The assembly source includes a low level file interface, but the higher level functions must be compiled from a FORTH disk. See the following section in the technical reference on "Modifying FORTH" for details. In order to switch from the FORTH disk to a screen file, type USING" <filename>" where <filename> is any legal, unambiguous MS-DOS filename. FORTH will attempt to open the file and determine if it is a file of FORTH screens. If all goes well, FORTH will tell you how many blocks are available in that file. The file will look just like the disk to FORTH, except its capacity will be smaller. Screen files may not span disks. If the specified file doesn't exist, FORTH will create it but will not allocate any space to it. The following example demonstrates the screen file access words. 8086/8088 FIG-FORTH User's Guide Page 12 Start FORTH, and type USING" TRYIT" FORTH will create a file named TRYIT.SCR and tell you that the file is empty. To use the file, you must allocate some space to it. This is done by entering 2 EXTEND EXTEND takes the number on the stack and adds that many blocks to the end of the screen file. In this case, the file is now 0+2 or 2 screens long (screens 0 and 1). If you were to try and list screen 2, you would get an error. Note that EXTEND does not put anything in the screens allocated; they contain whatever the disk held previously, but now they belong to your current screen file. Clear a working screen by entering the editor and filling screen one with blanks: 1 SCR ! EDITOR WIPE List the screen, select line 0, and enter some text: L 0 T P ( this is screen 0 line 1 in file TRYIT.SCR ) L Use FLUSH to save the changes, then type "L" again. The screen should be just as you left it. Try editing the definitions for STAR and MILKY-WAY onto this screen. When you finish editing, save it by typing EOF (End Of File) to close the file. EOF displays the directory entry of your file to verify that everything is allright. If the file is empty, EOF will notify you and then erase the file. You are now in limbo as far as the disk is concerned. If you try to access the disk, FORTH will remind you to specify which kind of disk access you want to do: file or FORTH disk. To list the screen again, tell FORTH to use TRYIT.SCR (USING" TRYIT"). Now FORTH should find a file with 2 blocks in it. And if you list screen 1, you will see your definitions, just as you left them. If you need more screens, use EXTEND as before to allocate more space. Remember to WIPE the screen as it will probably be full of nasty control characters for your terminal to choke on! Why not use screen 0? Well, FORTH can list screen 0, and you can edit text there, but if you try "0 LOAD", FORTH will 8086/8088 FIG-FORTH User's Guide Page 13 get very confused. When FORTH compiles block 0, it actually compiles input from the console. Thus, block 0 of each screen file cannot be loaded (but, see the following section for one use for screen 0). 4.3.4 Compiling Definitions As with editing, once you have opened a screen file, you can proceed exactly as you would with a FORTH disk. If you have edited some definitions onto Screen 1, compile them by typing 1 LOAD. If FORTH says "ok", test them as before. If there is an error, edit the definitions and try again. There is only one new word with regard to loading screen files. To make the process of selecting a screen file and loading it more convenient, use. LOAD" <filename>" LOAD" opens the specified file, and loads the screens starting with screen one. Since screen zero is just sitting there with nothing to do, LOAD" lists it before beginning the load with screen one. This is a good place for any special messages, advertisements, secret messages, etc. LOAD" is defined as simply: : LOAD" USING" ( code to list screen 0 ) 1 LOAD EOF ; If an error is encountered during the LOAD, that file will be the current screen file. 8086/8088 FIG-FORTH User's Guide Page 14 4.3.5 Other Functions There are several utility functions defined which make FORTH more convenient to use with the file system. These words apply only to MS-DOS disks and not to FORTH disks. 4.3.5.1 Changing the Default Drive As in COMMAND, typing A: or B: will change the default drive for all file access. 4.3.5.2 Directory Information Several utilities are available for using MS-DOS disks. Two words which list the disk directory are defined: DIR" <filename>" FILES" <filename>" DIR" gives a complete directory listing of each matching filename, similar to the MS-DOS DIR command. FILES" lists only filenames, five per line, much as the MS-DOS DIR command with the "/W" option. The exact interpretation of ambiguous filenames differs from COMMAND's. The filename must not be blank, and any part of the name left out defaults to "*". Thus, DIR" .SCR" = DIR *.SCR DIR" *" = DIR * DIR" ALL." = DIR ALL.* The trailing quote may be replaced with the carriage return, and in fact, must be replaced to list files with a blank extension: DIR" .<CR> =DIR *. DIR" INDEX.<CR>=DIR INDEX. 4.3.5.3 Erasing Files A function is provided to erase files: ERASE" <filename>" The use of this command is similar to the directory words 8086/8088 FIG-FORTH User's Guide Page 15 above, except that no part of <filename> has a default value. ERASE" will accept ambiguous filenames, and it displays the name of each file it erases. No warning is issued when the filename is "*.*", so beware! 4.3.5.4 Screen Transfer To assist in copying screens between FORTH disks and MS-DOS files, two utilities are provided: COPY>FILE and COPY>SCR. These function very simply. COPY>FILE directs all block reads to the FIG-FORTH disk, and all disk writes to the current screen file. COPY>SCR does the reverse. Then all you need is the usual words for moving screens around, and magically they appear at the destination. The actual copy operation is provided by the word #SCRCOPY, which takes the starting source screen, the starting destination screen and the number of screens to copy off the stack. Thus, USING" NEW" COPY>FILE ... 100 1 14 #SCRCOPY EOF would copy screens 100-113 on the FORTH disk to screens 1-14 in the file NEW.SCR. Note that after you type COPY>SCR or COPY>FILE, you can still LIST or INDEX the source disk if you forget which screens you want to copy. 4.3.5.5 Screen File Status To check on the status of the current screen file, you can use SCREENS /? If the screen file is in use, a display similar to the DIR" information is printed; for example, A:FORTH .SCR r w s 10240 06-28-1983 19:59 If the EOF command is given and then /? is repeated, the following would be printed: A:FORTH .SCR r w s showing that the file is not in use. The "r w s" indicate that this is a screen or random access file (s), which may be both read from (r) and written to (w). An interesting discrepancy may arise between the DIR" report and the /? information. 8086/8088 FIG-FORTH User's Guide Page 16 Examine the following session: USING" NEW" empty file 5 EXTEND ok DIR" NEW.SCR" B:NEW .SCR 0 06-29-1983 0:26 1 file ok SCREENS /? B:NEW .SCR r w s 5120 06-29-1983 0:27 ok EOF ok B:NEW .SCR 5120 06-29-1983 0:27 1 file ok SCREENS /? B:NEW .SCR r w s ok The differences in the file size and time fields reflect the operating system buffering the physical disk output. The /? display is taken from the file control block in memory, which is immediately updated, while the DIR" display is taken from the directory and is not updated until data is written to the disk when the file is closed by EOF. 8086/8088 FIG-FORTH User's Guide Page 17 4.3.5.6 Notes A few features of the above discussion bear further emphasis. * NEVER change the disk FORTH is using for screens while the file is open. Changing disks haphazardly is a bad practice in almost all cases, not just for FORTH. As can be seen above, the information kept on the disk is not always accurate. If the disk is changed, the file parameters kept in memory will be separated from the directory entry for the file, and disaster is almost certain to result. * In light of the above comments, note that you may FLUSH FORTH's disk buffers, but not MS-DOS's disk buffers. Thus your disk buffers are not guaranteed to be on the disk until you close the file using EOF. If the file interface is loaded, BYE is redefined to execute EOF before exiting, to force any updated buffers to be saved. * Only one screen file may be active at once. FORTH checks this and will not allow another USING" while the SCREENS file is in use. This restriction only applies to screen files. * The FORTH disk is the default state after COLD, but before an EOF. You must specifically request access to a screen file. Once you use a screen file, FORTH blocks any FORTH disk access until you request it using SWITCH. Accessing an MS-DOS disk as a FORTH disk probably won't destroy it, however, FORTH will probably get upset and quit talking to you. FORTH tries to remind you to pay attention, but it doesn't try to protect you: the burden is on YOU to keep track of what you are doing! * There is a convention for the names of the disk functions. Since there are two names for each file (see below) there are two ways to refer to a file. Names which begin with a "/" expect an address on the stack. Names which end in a double-quote expect a filename, delimited by a trailing quote, to follow. The function that assigns filenames to files, therefore, has both: /IS". 8086/8088 FIG-FORTH User's Guide Page 18 4.4 Modifying FORTH FORTH is an extremely flexible language. With a little effort you can make it your own personal environment. In addition, since you have the assembly source you can change the inner workings, making it more efficient. The following discussion is not complete, but serves only as an introduction. Exploring the territory is half the fun! 4.4.1 FORTH Extensions One of the nice things about FORTH is the ability to extend the language. To complement this extensibility, you can save the new FORTH in an executable file and the extensions become immediately available. Only two things are necessary to accomplish this: first, FORTH's cold start parameters must be updated; and second, the memory image of the modified FORTH must be saved in a file. This is how the FORTH.COM file was constructed for distribution. Updating the cold start parameters is accomplished by the FORTH word NEW. Saving the new version can be done in two ways: first, using DEBUG and second, the FORTH word SAVE-FORTH" <filename>". The FORTH word SIZE? will tell you the size of the FORTH kernel for writing from DEBUG. To use SAVE-FORTH, first execute NEW to lock the changes. Make sure no files are open before executing NEW, otherwise they will appear to be open when the new FORTH executes. Then define an output file and use SAVE-FORTH to write itself to the file. Since the file was defined after NEW, it will not appear in the new version. Study the following hypothetical example: 9 LOAD 100 LOAD 108 LOAD ok NEW ok current version is A new version (A-Z)? Bok >FILE S4 ok S4 /SAVE-FORTH" X4TH.COM" B:X4TH .COM 12521 06-29-1983 0:27 ok Note that because the FIG-FORTH disk is the default state, you must always modify and load the file definitions from a FORTH disk. If you FORGET the file words, you can only use the FORTH disk! 4.4.2 Patching Many of the parameters which affect the operation of FORTH are placed in the boot parameter area at the low end of FORTH. These may be freely modified using DEBUG, or from within FORTH. On execution of COLD, these parameters will 8086/8088 FIG-FORTH User's Guide Page 19 be used to initialize the interpreter. The patches can then be made permanent as described above. For example, the following will change the FORTH backspace key: KEY 14 +ORIGIN ! After you type this and hit return, FORTH will wait for you to hit a key. The key you type will be placed in the boot parameters and will be recognized as your backspace. The other parameters in this area are clearly commented in the assembly source, should you want to patch any of them. 4.4.3 Assembly Source Modifications Re-assembly of FORTH is the least desirable form of modification. It is slow and can be difficult to debug. However, there are modifications which are only possible in this way. A great deal of time has gone into adding comments to the assembly source so that you can understand the way FORTH works. Almost all of the comments appearing in the FIG listing are in the new listing, along with some additional comments. There is more information on the assembly source in the technical reference portion of this documentation. Be aware of two problems here: first, it is very easy to lose track of the changes you make. so document and comment each modification. Second, more changes make your version of FORTH more unique (or maybe just strange) and any definitions using that feature less portable. Don't add bells and whistles just to be different. 8086/8088 FIG-FORTH User's Guide Page 20 5.0 Technical Reference This section describes changes and modifications to the FIG-FORTH model. It is not an explanation of the FIG model, nor of how FORTH works. The user should refer to the FIG installation manual for further information. 5.1 Assembly Source The FIG assembly listing on which this version is based was written for the CPM/86 8086 assembler. For MS-DOS, the FIG listing was translated into source for Seattle Computer Products 8086 assembler. Since the latter assembler is peculiar to SCP systems, the code was translated again into source for Microsoft's MACRO-86 macro assembler, to be portable to any MS-DOS environment. Several features of MACRO-86 were used to provide greater flexibility. First, macros were written to build dictionary headers for each definition. These macros make setting up the dictionary entries convenient, but more importantly, they calculate the link fields. Because the links are no longer based on specific labels in the source, the dictionary can be split into several files which are then INCLUDED at the appropriate points. This allows great flexibility and modularity in assembling FORTH. 5.1.1 Source File Organization The source is now broken into several separate files: * 4TH-MAIN.ASM This is the primary file which INCLUDES the others during assembly. It contains the inner interpreter, code-level kernel, and most of the FORTH vocabulary. * 4TH-SYSD.ASM This file contains (almost) all of the code which is operating system or hardware dependent. If you wanted to transport FORTH to a different system, most of the changes would be in this file. * 4TH-DISK.ASM This file is INCLUDED by 4TH-SYSD and contains the actual disk interface for reading/writing disk sectors. * 4TH-FILE.ASM Also (optionally) INCLUDED by SYSD, this file has all of the words that deal with files at the operating system level. This code is only assembled 8086/8088 FIG-FORTH User's Guide Page 21 if the FILES option is set to TRUE. * 4TH-XTNS.ASM These definitions are code-level extensions of the FORTH dictionary. These include array addressing primitives, long fetch and store operators and the port i/o words. MATCH is also in this file. This file is only assembled if the EXTEND option is TRUE. * 4TH-OPTS.H The assembly options are located in this header file, and are symbols which begin with the underscore character. These are global parameters and are used by other modules. All other equates and variables should be local to the module where they are defined. It is unfortunate that the modules cannot be separately assembled and linked. The present system requires a lot of memory and about 5 minutes to assemble (on an 8MHz 8086 using 8" ssdd disks). This is really tedious for making small changes! 5.1.2 Macros The macros necessary to assemble FORTH are in the file 4TH-LIB.MAC. Comments in this file explain the function of each macro. Beside the dictionary macros, there are two macros to do branches in the threaded definitions. The actions of the macros should be clear after studying their definitions and the manner in which they are used in the code. 5.1.3 Comments The SCP assembler source was rather sparsely commented. This omission has been rectified by copying all of the FIG listing comments, plus some additional comments, into the MACRO-86 code. In addition, each entry in the dictionary has a comment in the following form: ;=AB <name> <description> <stack effects> where A is a letter indicating the type of dictionary entry, and B is a character indicating whether the function has been added or modified. This scheme allows automatic glossary generation using a text editor or search utility. 8086/8088 FIG-FORTH User's Guide Page 22 The dictionary entry types are: C = code-level definition : = colon definition # = constant ? = variable U = user variable The B character is either a blank, a plus, or an asterisk; indicating that the definition is unmodified, added, or modified, respectively. 5.2 Modifications The changes to the FIG listing fall basically into two categories: changes to clean up the disk interface and manage buffers more efficiently, and changes to route the i/o functions through execution vectors. The sections below describe specific changes to the FIG model. Each section corresponds to one in the FIG-FORTH installation manual. Any changes to that part of the model are listed there. 5.2.1 Boot Parameters BSIN was changed to 127 - ASCII DEL. 5.2.2 Machine Code Definitions Code added to (FIND) to handle word-aligned definitions. May be disabled by setting the option ALIGN to FALSE. 5.2.3 High-Level Utility Definitions 1+ and 2+ were changed to code definitions. TRAVERSE was modified to handle word-aligned LFA's. PFA was changed to handle word-aligned PFA's. EXPECT backspace was made destructive. ID. was modified to reset MSB of last character. CREATE can compile dictionary headers with word-aligned LFA's. If DP is odd after compiling the name field, DP is incremented so that the rest of the definition lies is word addressable. If byte values such as character strings are subsequently compiled into the definition, the alignment may be lost. Note that the length byte at NFA still gives the exact length of the name, but not necessarily the displacement to the LFA. The alignment may be 8086/8088 FIG-FORTH User's Guide Page 23 disabled by setting the ALIGN option to FALSE at assembly time to save space. QUIT prints lower case "ok". ABORT prints the user version as well. COLD sets execution vectors. All system dependent initialization is in a subroutine called SYSINIT, located in 4TH-SYSD.ASM, which is called just prior to starting the inner interpreter. 5.2.4 Installation Dependent Code 5.2.4.1 Console I/O KEY, EMIT, and CR were changed to use the execution vectors @KEY, @EMIT, and @CR respectively. These vectors are initialized to the CFA's of (KEY), (EMIT) and (CR); but may be changed by storing new CFA's in the vectors. Two options in 4TH-OPTS.H affect console i/o: DIRECTCON and IOBITS. If DIRECTCON is TRUE, console i/o is performed by MS-DOS function six and seven, which ignore all special characters. Thus, if you have an application which has to respond to ^P, for example, you should re-assemble with DIRECTCON set to TRUE. IOBITS is an equate which determines how many bits to send/receive. Normal ASCII terminals don't use the MSB, so IOBITS should be seven. However, the IBM-PC uses all eight bits, so IOBITS should be eight. DIRECTCON also disables ^C interrupts, except during printer output. 5.2.4.2 Printer I/O The variable controlling printer output was changed to PRINTER. If PRINTER is zero, no printer output occurs. If PRINTER is positive, all console output also goes to the printer. If PRINTER is negative, output normally going to the console is sent only to the printer. 5.2.4.3 Disk I/O The code to interface to the disk was factored into two parts. All functions that know something about the physical characteristics of the disk are in the 4TH-DISK.ASM file. Every other function knows only that disk blocks are 1024 bytes long. This means that BLOCK-READ/WRITE must always deliver 1024 bytes and not one physical sector. 8086/8088 FIG-FORTH User's Guide Page 24 The disk read/write routines (BLOCK-READ, BLOCK-WRITE) were changed to use the execution vectors @BLKRD and @BLKWRT. For normal FORTH disk i/o, @BLKRD and @BLKWRT point to BLKRD and BLKWRT. For screen file access, these vectors are set to /BLOCK-READ and /BLOCK-WRITE. The variables DRIVE, RECORD, REC/BLK and DTA are set to the parameters used for each disk access and may be examined if an error occurs. The variable DISK-ERROR is set to indicate the success or failure of each disk operation. If DISK-ERROR is zero, the operation was successful. Otherwise DISK-ERROR has the MS-DOS error code as described in its documentation, except that write errors are converted to negative numbers. The buffer management was also changed slightly. When BUFFER has to flush a dirty block to the disk, it checks and flushes ALL dirty buffers. This requires very little additional overhead, and it is much more efficient for copying multiple blocks. 5.2.5 High-Level Definitions 5.2.6 System Tools 5.2.7 RAM Workspace 5.2.8 Memory Map The memory map was extended to use all 64K (LIMIT=0), and 8 1K byte block buffers. 5.2.9 Other COLD sets the ^C interrupt vector to the address of a code fragment which, on receiving control after you hit ^C, examines the variable @BREAK. If @BREAK is zero, the interrupt handler simply returns from the interrupt and execution continues. Unfortunately, a "^C" is always sent to the console, and the key is not passed to FORTH. If @BREAK is non-zero, the interrupt handler vectors the inner interpreter to the (presumed CFA) address in @BREAK. @BREAK is set at assembly time to the CFA of (ABORT), it is not initialized by COLD. If the DIRECTCON option is selected, almost all ^C processing is disabled. The only time a ^C interrupt can occur is during printer output. BYE exits via INT 20H 8086/8088 FIG-FORTH User's Guide Page 25 5.3 Additions Two new features have been added in this version of FIG FORTH. Command line argument interpretation allows you to pass instructions to FORTH from COMMAND. Thus, you can run FORTH from a batch file if the program doesn't require any terminal input. The file interface allows FORTH to share information with other MS-DOS programs and utilities. 5.3.1 Command Line Interpretation When FORTH starts execution, it copys any string of text on the command line to the terminal input buffer, and interprets it just as if you had typed it. 5.3.2 File Interface The goal in developing the file interface was to allow FORTH useful access to MS-DOS files, not simply the random access screens. The constraint was that it had to be accomplished with a minimum of change to the FIG model. This discussion is not as complete as it could be. The reason for this is that the details will probably change. While the overall design is (hopefully) sound, the fine points are not completely worked out. As they are applied, they will certainly be improved. There are two parts to the file interface: the low level functions defined in 4TH-FILE.ASM and the high level words in FILES.SCR. The low-level functions are little more than MS-DOS function calls with FORTH headers. The high-level definitions do most of the work, making it easier to modify the interface. The words defined in FILES.SCR allow you to define files in much the same way you define variables. After a file has been defined, the name is used to refer to it. The name acts just like a variable, returning an address. The address returned is a pointer to the file header and file control block, or FCB. The header is a word of data where the file's attributes are kept, this header address is referred to as the file descriptor, or FD. These attributes are only used by FORTH, MS-DOS never sees them. At present, the only attributes are: read, write, sequential/random access and open. Following the header is the FCB which MS-DOS uses while the file is open. 8086/8088 FIG-FORTH User's Guide Page 26 The first part of the FCB is the filespec. This is the drive, filename and extension for the file, and is the name by which MS-DOS refers to the file. Before opening a file, these fields must be filled in. Assigning the filename is accomplished by two methods, one for interactive use and one for use inside definitions. The word FNAME takes a target address and a mode number on the stack. It then parses the string at PAD (actually PAD+1, PAD holds the count byte), and returns a flag which is true if the filename was ambiguous. If FNAME finds that the given filename is illegal (or null) it prints an error and aborts. To assign a filename to a file from the terminal, the word /IS" is provided. This function takes an fd off the stack and assigns the following word in the input stream as the filename. The /IS" function can be used in a definition, but it can't be used to assign a filename to a file without console input. Once the file has been defined, and has a name, it can be opened or created using /OPEN, or /CREATE. The file can be closed using /CLOSE. For character files, /GETC and /PUTC are provided to read/write one character; and /READ and /WRITE transfer a number of bytes at once. Screen files use /BLOCK-READ and /BLOCK-WRITE. These functions are called indirectly through BLOCK-READ or BLOCK-WRITE. This reference is admittedly incomplete. For further information, study the glossary for 4TH-FILE and the FORTH code for the file interface. 8086/8088 FIG-FORTH User's Guide Page 27 6.0 Glossary This section is a glossary of words added or changed, relative to FIG-FORTH v1.0. The name of the word is given, then its stack effects, then the type of definition, where the letter indicates the type of definition: C = code-level definition : = colon definition # = constant ? = variable U = user variable and the second letter indicates whether the definition was added (+) or modified (*). And, finally, the file where the word is defined. 8086/8088 FIG-FORTH User's Guide Page 28 6.1 Assembly Listing Definitions (2ARR) n1 n2 PFA -- addr C+ XTNS Two dimensional word array primitive compiled by 2ARRAY. The address of the array element at row n1, column n2, of an array beginning at addr+4 is left on the stack. It is assumed that the number of columns is stored at addr. The contents of addr+2 could hold the number of rows (perhaps for error checking), but it isn't used in the calculation. (2CARR) n1 n2 PFA -- addr2 C+ XTNS Two dimensional byte array primitive compiled by STRINGS. The address of the array element at row n1, column n2 of an array beginning at PFA+4 is left on the stack. It is assumed that the row size is at PFA. The contents of PFA+2 could hold the number of rows, but it isn't used in the calculations. (ARRAY) n PFA -- addr C+ XTNS Integer array primitive used by ARRAY. The address of the nth element of the array beginning at PFA+2 is calculated and left on the stack. The length of the array is stored at PFA. (BLKRD) -- C+ DISK Block read primitive called by BLKRD. This function calls the absolute disk read function (INT 25) to access the disk. This function transfers REC/BLK records, starting at RECORD on DRIVE to DTA. The code returned by the interrupt is placed in DISK-ERROR, zero indicating success. (BLKWRT) -- C+ DISK Block write primitive called by BLKWRT. This function transfers REC/BLK records on DRIVE starting at RECORD to DTA. The return code from INT 26H is negated and placed in DISK-ERROR, zero means success. (CARR) n PFA -- addr C+ XTNS Byte array primitive compiled by CARRAY. The address of the nth character in the array beginning at PFA+2 is calculated and left on the stack. The length of the array or the current length of the string may be left at PFA. 8086/8088 FIG-FORTH User's Guide Page 29 (CLOSE) FCB -- f C+ FILE Primitive function to close FCB using DOS function 10H. The flag is zero if successful, 0FFH if not. (CREATE) FCB -- f C+ FILE Create and open a file as specified in FCB using DOS function 16H. The flag returned is zero if successful, 0FFH if not. (FBLKRD) FCB n -- f C+ FILE File block read primitive. This function reads n blocks from an open FCB. The blocks read are the size specified in the record size field of the FCB. For normal screen files, n is always 1 and the record size is set to 1024 bytes. (FBLKWRT) FCB n -- f C+ FILE Write n blocks to the file specified by FCB. See (FBLKRD) above. (FIND) a1 NFA -- [PFA b] f C* MAIN (FIND) was modified to handle aligned dictionary headers (only when ALIGN is true). The address list following the header is aligned by inserting a NOP (90H) after the last character of the name field. (FIND) must take this into account when looking up a name. (FNAME) FCB addr1 n -- addr2 f C+ FILE Parse the string at addr1 as a filename using mode n, and assign it to FCB. The first character not parsed and an ambiguous filename are left on the stack. This function uses DOS function 29H, which defines the modes. (OPEN) FCB -- f C+ FILE Open the specified FCB. The flag returns the success or failure of the operation: zero if successful, 0FFH otherwise. (READ) FCB addr -- f C+ FILE Sequential read primitive. Transfers the next record in the file specified by FCB to addr. The status of the operation is returned in the flag f. The flag is zero if successful, 0FF if not. (WRITE) FCB addr -- f C+ FILE Sequential write primitive. Writes the next record of the file specified by FCB from addr. The flag returned by DOS function 15H is left on the stack. 8086/8088 FIG-FORTH User's Guide Page 30 (XOF) n1 n2 -- [n1] C+ XTNS Control structure primitive compiled by OF. If the case being scanned for (n1) matches the current case (n2), the tag n1 is dropped and the FORTH words following the branch compiled by OF are executed. If the case tags don't match, n1 is left on the stack and the branch is executed to check the next case. +BUF addr1 -- addr2 :* MAIN Advance the buffer pointer addr1 to the next buffer at addr2. 1- n -- n-1 C+ MAIN Subtract one from the item on top of the stack. 2- n -- n-2 C+ MAIN Subtract two from the item on top of the stack. ?FIRST FCB addr -- f C+ FILE Search the disk directory for the first occurance of FCB. The flag returned is zero if none are found, 0FF otherwise. If a match is found, its directory entry is placed at addr. ?NEXT addr FCB -- f C+ FILE Search for the next occurance of FCB. The search FCB must previously have been set up by ?FIRST. If a match is found, f will be 0FFH and the matching directory entry will be left at addr. @BLKRD - addr U+ MAIN Execution vector holding the CFA of a function to read one block from the disk. This vector is either BLKRD for FORTH disk access or FBLKRD for screen file access. BLOCK-READ uses this vector. @BLKWRT - addr U+ MAIN Execution vector holding the CFA of a function to write one block to the disk. This vector is either BLKWRT for FORTH disk access or FBLKWRT for screen file access. BLOCK-WRITE uses this vector. @BREAK -- addr ?+ SYSD Execution vector holding the CFA of the function to be executed on input if a ^C. If @BREAK is zero, the interrupt handler simply returns, effectively ignoring the interrupt. 8086/8088 FIG-FORTH User's Guide Page 31 @CR -- addr U+ MAIN Execution vector to output a newline, usually carriage return/linefeed. COLD initializes @CR to the CFA of (CR). @EMIT -- addr U+ MAIN Execution vector to do character output. Initialized by COLD to the CFA of (EMIT). @KEY -- addr U+ MAIN Execution vector to do character input. Initialized by COLD to the CFA of (KEY). B/SEC -- n C+ FILE Calls DOS function 1BH and returns the number of bytes per physical disk sector. BLK/DRIVE -- n #+ DISK Constant returning the number of 1K disk blocks per drive. BLKRD addr blk -- :+ DISK This function reads block blk to addr. This is basically an interface between the BLOCK-READ function and the (BLKRD) functions. BLKWRT addr blk -- :+ DISK This function writes block blk from addr. This is basically an interface between the BLOCK-WRITE function and the (BLKWRT) functions. BLOCK n -- addr :* MAIN BLOCK was modified to check for a disk error. BLOCK-READ addr blk -- :+ MAIN Read one block to addr. Calls the function whose CFA is in @BLKRD to do the actual transfer. BLOCK-WRITE addr blk -- :+ MAIN Write one block from addr. Calls the function whose CFA is in @BLKWRT to do the actual transfer. BUFFER n -- addr :* MAIN This function was modified to flush all dirty buffers when one is found. COLD -- :* MAIN Added code to initialize execution vectors. 8086/8088 FIG-FORTH User's Guide Page 32 CR -- :* MAIN Output a carriage return/linefeed by calling the function whose CFA is in @CR. CREATE -- :* MAIN Create a dictionary header for the next word in the input stream. CREATE was modified to align the address list. The ALIGN option must be selected for this to occur. D&RCALC n -- :+ DISK Set DRIVE and RECORD for block n. This function is called by BLKRD/BLKWRT to set up for (BLKRD)/(BLKWRT). DATE! n1 n2 n3 -- C+ XTNS Date set operator. The parameters are n1=month, n2=day, n3=year. If any of the parameters are out of range, no change is made. DATE@ -- n1 n2 n3 C+ XTNS Date fetch operator. The parameters are n1=month, n2=day, n3=year. If any of the parameters are out of range, no change is made. DISK n -- n2 C+ FILE Set the current default drive to n. Drive A is zero, B is one. The number of drives, n2, is left on the stack. DISK@ -- n C+ FILE Return the current default drive number. DTA -- addr ?+ MAIN Variable holding the address of the last disk transfer operation. This variable is set by R/W for use by the transfer functions. EMIT c -- :* MAIN Function to do character output. Calls the function whose CFA is in @EMIT to do the actual output. EMPTY-BUFFERS -- :* MAIN This function was modified to set emptied buffers to block 32767. FIG-FORTH set them to zero. FLUSH -- :* MAIN FLUSH was also modified so that empty buffers are assigned to block 32767. 8086/8088 FIG-FORTH User's Guide Page 33 FDEL FCB -- f C+ FILE Delete the file specified by FCB. The flag returned is zero if successful, 0FFH otherwise. FREN addr -- f C+ FILE Rename the file according to the special FCB at addr. See the DOS function 17H for details on how this is set up. KEY -- c :+ MAIN Character input function. KEY calls the function whose CFA is in @KEY to get the character. L! n seg off -- C+ XTNS L@ seg off -- n C+ XTNS LC! n seg off -- C+ XTNS LC@ seg off -- b C+ XTNS Intersegment fetch/store operators. These are similar to the usual FORTH fetch/store words, except they use a double-word address. Note that the absolute location accessed is seg*16+offset. MAXBLOCK -- n #+ DISK Constant returning the highest legal block number. That is, BLK/DRIVE*(MAXDRIVE+1)-1. MAXDRIVE -- n #+ DISK Constant returning the highest legal drive number. MYSEG -- seg C+ MYSEG This word returns the value of FORTH's current segment. This allows the long fetch/store operators to access locations inside FORTH easily. NFA PFA -- NFA :* MAIN PFA NFA -- PFA :* MAIN These functions can adjust for aligned definitions, if ALIGN is selected during assembly. PRINTER -- addr ?+ MAIN Flag controlling printer output. If PRINTER is zero, nothing is sent to the printer. If PRINTER is positive, output to the console also goes to the printer. If PRINTER is negative, output normally going to the console will be sent to the printer only. Note that this is independent of the ^P/^N printer echo! 8086/8088 FIG-FORTH User's Guide Page 34 R/W addr blk f -- :* MAIN This function was modified to simply pass the addr and blk on to the BLOCK-READ or BLOCK-WRITE functions. REC/BLK -- n #+ DISK Constant returning the number of disk records required to fill one 1024 byte buffer. All disk accesses look to FORTH like they transfer 1K of data. RECORD -- addr ?+ MAIN Variable holding the disk record number where the last block accessed began. That is, if the last block accessed was 2, then record would contain 2*REC/BLK. This variable is set by D&RCALC for use by (BLKRD)/(BLKWRT). SAVBUF addr -- :+ MAIN This function saves the buffer at addr if it has been updated. The buffer is flushed but not emptied. SAVE-BUFFERS -- :+ MAIN This function flushes all the buffers but doesn't empty them. SAVE-BUFFERS is called by BUFFER when it finds a dirty buffer. TIME! n1 n2 -- C+ XTNS TIME@ -- n1 n2 C+ XTNS Set/fetch the system time. The parameters are n1=[sec/csec], n2=[hr/min]; each quantity is a byte, but the four are packed into 2 words. Note that the low byte of the top stack item has the minutes, the high byte holds the hours, and so on. If any of the parameters are out of range, there is no effect. 8086/8088 FIG-FORTH User's Guide Page 35 6.2 Deleted Definitions The following words were deleted from the FIG listing: EPRINT SEC SECRD SECWT SET-DRIVE SET-IO T&SCALC TRACK 8086/8088 FIG-FORTH User's Guide Page 36 6.3 High-level Extensions The following words were added by compiling FORTH screens and saving the new version of FORTH. The FORTH source is included in the screen files. ARRAY n -- :+ ARRAYS.SCR 2ARRAY n1 n2 -- :+ ARRAYS.SCR One and two dimensional integer array defining words. Used as: 3 10 ARRAY WEIGHTS to define a 3 by 10 array of integers which can be accessed by: 0 0 WEIGHTS @ 2 9 WEIGHTS ! Which would replace the last element by the first. STRING n -- :+ ARRAYS.SCR STRINGS n1 n2 -- :+ ARRAYS.SCR One and two dimensional byte array defining words. Similar to the array definitions above, but are accessed by C@ and C!. CASE OF ENDOF ENDCASE :+ CASE.SCR These words add a case construct to FORTH. They have been documented in several different places. Quite a few examples are found in the ASSEMBLER screens. DUMP addr1 -- addr2 :+ UTIL.SCR This word displays the contents of memory from addr1 to addr2-1. The address left on the stack can be used to continue dumping without having to keep track of the address. The dump is given in the current number base. A variable named SEGMENT is used as the base, with addr1 then being an offset in that segment. SEGMENT is initialized to MYSEG. NEW -- :+ UTIL.SCR NEW updates the start-up parameters to reflect the current state of FORTH. This allows compiled definitions to be retained when COLD is executed. Note that if you FORGET the added words after executing NEW, the start-up parameters will be wrong, and NEW must be run again before a cold start. 8086/8088 FIG-FORTH User's Guide Page 37 SIZE? -- :+ UTIL.SCR Shows the current size of the FORTH dictionary, and the free space remaining. This is primarily useful for saving modified FORTHs. 8086/8088 FIG-FORTH User's Guide Page 38 7.0 Future Extensions This version includes almost all of the extensions I had planned to implement in the "immediate future". It will be work enough fixing bugs and tuning the revisions in this package, without shooting for major revisions. But, my list for the questionable future remains intact: Cross/target compiler Code level floating point/8087 support Multisegmented > 64K Multitasking Tree structured vocabularies/file system High-level interrupt handling Should any of these interest you, or spark any comments, I would be happy to talk or trade. Specifically, I would really love to have some kind of floating point package: this is my last excuse for writing ANYTHING in BASIC! The MACRO-86 assembler is really cumbersome at this kind of work, and FORTH is ideally suited to writing new FORTHs. If I can get metaFORTH going, that would make a nice project. 8086/8088 FIG-FORTH User's Guide Page 39 8.0 FORTH Sources The following are sources of information regarding the implementation and use of FORTH. * STARTING FORTH, by Leo Brodie. Prentice Hall 1981 This is probably the best introductory book on FORTH. * Byte, vol. 5 no. 8, August 1980 This issue was devoted to FORTH, and contains good discussions of defining words and FORTH internals. * Dr. Dobb's Journal, vol. 6 no. 9, September 1980 Dr. Dobb's Journal, vol. 7 no. 9, September 1981 These issues were both devoted to FORTH topics. * Various publications of the Forth Interest Group: Fig FORTH Installation Guide, FORTH DIMENSIONS bi-monthly journal. * Mountain View Press P.O. Box 4656, Mountain View, CA 94040 (415) 961-4103 This company has a large selection of software and publications for sale. 8086/8088 FIG-FORTH User's Guide Page 40 Appendix A - Using Execution Vectors The i/o functions in this version of FORTH have been changed to use execution vectors. An execution vector is a simple way to allow the user to substitute a different function for the function which is vectored in this way. A.1 Concepts The way an execution vector works is quite simple. If you are familiar with the concept of pointers to data, this is nothing new, for execution vectors are only pointers to functions. The pointer may be changed to hold the address of any function, and as long as the specified function expects and returns the same parameters and result, no one knows the difference. The FORTH interpreter functions on this principle: it inputs a word, looks it up in the dictionary, and executes it. The interpreter can totally ignore the action taken by the words it executes. In standard FORTH, the function which executes a word is called EXEC. The address that EXEC expects on the stack differs between FORTHs. In FIG-FORTH, the address must be a Code Field Address, or CFA. The address returned by the dictionary search words ( ' and -FIND) is a Parameter Field Address (PFA). Thus, to look up a word in the dictionary, you can type ' MY-WORD but to find and execute MY-WORD, you would type ' MY-WORD CFA EXEC This is totally equivalent to just typing MY-WORD. In this way, any function can be vectored through a variable: the variable holds the CFA of the function to be executed. Instead of executing the function directly, the variable is fetched and the CFA stored there is executed. Now, instead of jumping directly to code which sends a character to the console, KEY fetches the variable @KEY, and does whatever is at that CFA. The definition of KEY is thus : KEY @KEY @ EXEC ; To change the function of KEY, you just store a different CFA in @KEY. The new function can be defined after KEY, and any function which uses KEY will now call the new function. The danger here should be obvious: if the substitute 8086/8088 FIG-FORTH User's Guide Page 41 Appendix A - Using Execution Vectors function doesn't have the same stack effects as the standard function, FORTH is going to get really confused. A.2 An Example Although this arrangement is slightly more complex, the power and flexibility make it well worth the extra effort. The following example should make this clear. Suppose you want to do all input in capital letters only. You could write your own specialized input routine, or simply define an upper-case-only version of KEY and redirect KEY to that function. Here is the definition for the new KEY: : UC-KEY (KEY) DUP 96 > OVER 123 < AND IF ( a-z ) 32 - THEN ; Now all you have to do is set @KEY to point to your function: ' UC-KEY CFA @KEY ! and any lower case letter will be converted automatically to upper case. To restore KEY to the original action, restore @KEY to (KEY): ' (KEY) CFA @KEY ! Note that UC-KEY still calls (KEY) to get the character. While this is usually the case, it is not necessary: you could change KEY to get characters from any source. Also, be careful that you don't call the vectored function from within your replacement. If KEY had been used instead of (KEY) in the definition above, once @KEY had been re-assigned you would have a good example of infinite recursion! Actually it isn't infinite - FORTH dies rather quickly... This discussion applies to all of the i/o words, except ?TERMINAL. The block i/o functions are re-assigned in this way to use the screen files. There are more elegant ways of implementing execution vectors, which bypass the need for separate variables, but they require new defining words which would have been inconvenient to define in the assembler source. 8086/8088 FIG-FORTH User's Guide Page 42 Appendix B - Building FORTH.COM The following example serves several functions. It is a real session with FORTH, it shows how the FORTH.COM file was constructed, and, it demonstrates how to modify and save new versions of FORTH. After assembling the FORTH source, you are left with a bare kernel. To add the utilities, editor and file handling functions, several things have to be done: 1) The file interface screens must be transferred to a FORTH disk. This process involves using DEBUG to load the file and write it to the FORTH disk. 2) The file interface is LOADed from the FORTH disk. 3) The utilities and editor are /LOAD"ed from their files. 4) FORTH is reset to make the additions permanent, and the version number is changed. 5) The utilities for saving FORTH are loaded and used to write the new FORTH to a .COM file. The following session was copied from a listing of the commands to build FORTH.COM. An ellipsis indicates that part of the listing has been left out. This example assumes that you have a FORTH disk in drive A, and your FORTH system disk with FORTH.COM and the screen files in drive B. B:DEBUG FILES.SCR -W 100 0 64 20 -Q B: Here, DEBUG has loaded the MS-DOS file interface screens in FILES.SCR and then written the screens to disk A starting at screen 100. This assumes that one record holds one screen. You will have to adjust the record numbers if this is not the case. 8086/8088 FIG-FORTH User's Guide Page 43 Appendix B - Building FORTH.COM B:4TH 8086 FIG-FORTH Version 1.0A 100 LOAD 102 LOAD BYE MSG # 4 ok LATEST ID. LOAD" ok After assembling FORTH and grabbing a snack while MASM chugs along, the resulting 4TH.COM is started. The newly copied screens residing on disk A are loaded, the last word now being LOAD". USING" FUTIL" last block in B:FUTIL.SCR is 10 ok 1 LOAD ok 2 LOAD ok 3 LOAD .DIR MSG # 4 ok 7 LOAD ok LATEST ID. COPY>SCR ok EOF B:FUTIL .SCR 11264 07-19-1983 2:37 ok The file interface allows FORTH to use the screen files. The utilities for listing the directory and erasing files are loaded. Also, the words for copying screens to and from FORTH disks are loaded from screen 7. USING" UTIL" last block in B:UTIL.SCR is 8 ok 8 LOAD ok 3 LOAD 4 LOAD 6 LOAD ok WORDS CURRENT and CONTEXT are FORTH WORDS TAB TABSTOP MORE? DLIST NEW SIZE? BASE? VOC? VOC. S? DEPTH ENDCASE ENDOF OF CASE #SCRCOPY SCRCOPY ASSIGN-BUF COPY>SCR COPY>FILE PAUSE ERASE" . . . EOF B:UTIL .SCR 9216 07-20-1983 19:18 ok More utilities, including NEW to update the COLD start parameters, are loaded from the UTIL screen file. The vocabulary listing word WORDS is tested, and then the file is closed. 8086/8088 FIG-FORTH User's Guide Page 44 Appendix B - Building FORTH.COM LOAD" EDITOR" last block in B:EDITOR.SCR is 6 FORTH, Inc. editor . . . editor loading, please wait... I MSG # 4 R MSG # 4 Current screen is 8 B:EDITOR .SCR 7168 07-19-83 2:53 ok The editor described in STARTING FORTH is loaded. Note that LOAD" first lists screen 0, then begins loading at screen 1, and finally closes the file when the load is complete. NEW current version is A new version (A-Z)? Bok USING" FUTIL" last block in B:FUTIL.SCR is 10 ok 4 LOAD ok EOF B:FUTIL .SCR 11264 07-20-1983 19:32 ok Here, the utilities to save FORTH are loaded. Note that any words defined after executing NEW will not be saved, and, that the file is closed before writing the new version. >FILE S4 S4 /SAVE-FORTH" FORTH.COM" B:FORTH .COM - w c 13687 07-20-1983 19:41 ok ok BYE B:FORTH 8086 FIG-FORTH Version 1.0B WORDS WHERE EDITOR LINE TEXT WORDS... EDITOR WORDS r u i s f... BYE END OF DOCUMENTATION